With a Kanzi Engine plugin you can extend the functionality of Kanzi Engine and set how Kanzi Studio shows the custom content you create:
In a Kanzi Engine plugin you can create custom nodes with custom property types. You can set how Kanzi Studio shows and lets users interact with these nodes.
To create a custom node with custom property types:
... KZ_METACLASS_END() static kanzi::PropertyTypeEditorInfoSharedPtr makeEditorInfo(); ...
PropertyTypeEditorInfoSharedPtr MyPlugin::makeEditorInfo() { return PropertyTypeEditorInfoSharedPtr( KZ_PROPERTY_TYPE_EDITOR_INFO( []() -> PropertyTypeEditorInfo::AttributeDictionary { PropertyTypeEditorInfo::AttributeDictionary dict; // Set the name that you want to use for your node in Kanzi Studio. dict.displayName = "My Node"; // Set the tooltip that you want to use in the Kanzi Studio Create menu. dict.tooltip = "This example custom node uses custom properties."; // Add the Horizontal Alignment and Vertical Alignment properties to the node. dict["AutomaticallyAddedProperties"] = "Node.HorizontalAlignment, Node.VerticalAlignment"; // Add the State Manager property as a frequently used property which users can add by clicking next to the property name. dict["FrequentlyAddedProperties"] = "Node.StateManager"; // Let the user add the Focus Scope property using the Add Property context menu or the context tab of the Add Properties window. dict["ContextProperties"] = "FocusManager.FocusScope"; return dict; }())); }
Create the custom property types and their metadata.
For example:
KZ_METACLASS_BEGIN(MyPlugin, Node3D, "CustomComponentType") KZ_METACLASS_END()
with
// String property static kanzi::PropertyType<kanzi::string> StringProperty; // String reference to a node static kanzi::PropertyType<kanzi::string> NodeRefByStringProperty; // String reference to a prefab static kanzi::PropertyType<kanzi::string> PrefabRefByStringProperty; // Shared pointer reference to a prefab static kanzi::PropertyType<kanzi::ResourceSharedPtr> PrefabRefBySharedPtrProperty; // Shared pointer reference to a material static kanzi::PropertyType<kanzi::ResourceSharedPtr> MaterialRefBySharedPtrProperty; KZ_METACLASS_BEGIN(MyPlugin, Node3D, "MyNode") // Add the property types to the class metadata. KZ_METACLASS_PROPERTY_TYPE(StringProperty) KZ_METACLASS_PROPERTY_TYPE(NodeRefByStringProperty) KZ_METACLASS_PROPERTY_TYPE(PrefabRefByStringProperty) KZ_METACLASS_PROPERTY_TYPE(PrefabRefBySharedPtrProperty) KZ_METACLASS_PROPERTY_TYPE(MaterialRefBySharedPtrProperty) KZ_METACLASS_END()
// Creates a string property.
// This example does not set the editor. If you do not set the editor, Kanzi Studio uses
// the default editor for this property type.
PropertyType<string> MyPlugin::StringProperty(kzMakeFixedString("MyPlugin.String"), "", 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "String";
));
// Creates a string reference to a node.
PropertyType<string> MyPlugin::NodeRefByStringProperty(kzMakeFixedString("MyPlugin.NodeRefByString"), "", 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Node Reference by String";
// When you set valueProvider to ProjectObject:Node3D,
// Kanzi Studio automatically uses the Node 3D selector editor.
metadata.valueProvider = "ProjectObject:Node3D";
));
// Creates a string reference to a prefab resource.
PropertyType<string> MyPlugin::PrefabRefByStringProperty(kzMakeFixedString("MyPlugin.PrefabRefByString"), "", 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Prefab Reference by String";
// When you set valueProvider to ProjectObject:PrefabTemplate,
// Kanzi Studio automatically uses the Prefab template selector editor.
metadata.valueProvider = "ProjectObject:PrefabTemplate";
));
// Creates a shared pointer reference to a prefab resource.
PropertyType<ResourceSharedPtr> MyPlugin::PrefabRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.PrefabRefBySharedPtr"), ResourceSharedPtr(), 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Prefab Reference by Shared Pointer";
// When you set valueProvider to ProjectObject:PrefabTemplate,
// Kanzi Studio automatically uses the Prefab template selector editor.
metadata.valueProvider = "ProjectObject:PrefabTemplate";
));
// Creates a shared pointer reference to a material resource.
PropertyType<ResourceSharedPtr> MyPlugin::MaterialRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.MaterialRefBySharedPtr"), ResourceSharedPtr(), 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Material Reference by Shared Pointer";
// When you set valueProvider to ProjectObject:Material,
// Kanzi Studio automatically uses the Material dropdown editor.
metadata.valueProvider = "ProjectObject:Material";
));
metadata.host
attribute. See host.You can create and configure custom message types which you use to add functionality to your application. For example, you can create a custom trigger and action which set a property of a custom node. When you are using Kanzi Connect you can use custom message types to get information about a Kanzi Connect server or service that your application uses.
In a Kanzi Engine plugin, you can create a custom message type which you show in Kanzi Studio as a trigger.
For example, to allow the Kanzi Studio user to add a trigger called On Fuel Level Changed which is set off when the fuel level of a custom node called Fuel Indicator changes:
// Represents message arguments of FuelIndicator.OnFuelLevelChanged message type. class OnFuelLevelChangedMessageArguments : public MessageArguments { public: KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(OnFuelLevelChangedMessageArguments, MessageArguments, "On Fuel Level Changed Message Arguments") KZ_METACLASS_END() }; // Define the message type of the FuelIndicator.OnFuelLevelChanged message. static MessageType<OnFuelLevelChangedMessageArguments> OnFuelLevelChangedMessage;
FuelIndicator.OnFuelLevelChanged
message when the fuel level changes:// Sends a FuelIndicator.OnFuelLevelChanged message. void onFuelLevelChanged(int fuelLevel) { OnFuelLevelChangedMessageArguments messageArguments; dispatchMessage(OnFuelLevelChangedMessage, messageArguments); }
FuelIndicator.OnFuelLevelChanged
message:MessageType<FuelIndicator::OnFuelLevelChangedMessageArguments> FuelIndicator::OnFuelLevelChangedMessage(kzMakeFixedString("Message.FuelIndicator.OnFuelLevelChanged"), KZ_DECLARE_EDITOR_METADATA ( // Set the name of the message the way you want to show it in Kanzi Studio. metadata.displayName = "On Fuel Level Changed"; // Set the tooltip for the message. metadata.tooltip = "Fuel Indicator sets off this trigger when its level changes."; // Set the category under which this message is listed in the triggers list. metadata.category = "Custom Controls"; // Do not show the message in the trigger actions dropdown menu. metadata["Sendable"] = "False"; ));
In a Kanzi Engine plugin, you can create a custom message type which you show in Kanzi Studio as an action.
For example, to allow the Kanzi Studio user to add to a trigger an action called Update Level which shows the level of a custom node called Fuel Indicator in a Text Block 3D node:
// Represents the message arguments of the FuelIndicator.UpdateLevel message.
class FuelIndicatorUpdateLevelMessageArguments : public MessageArguments
{
public:
KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(FuelIndicatorUpdateLevelMessageArguments, MessageArguments, "Fuel Indicator Update Level Message Arguments")
KZ_METACLASS_PROPERTY_TYPE(FuelIndicatorLevelProperty)
KZ_METACLASS_END()
// The property type which represents the value of the Fuel Indicator node.
static PropertyType<int> FuelIndicatorLevelProperty;
// Returns the value of the Fuel Indicator message argument.
int getFuelIndicatorLevel()
{
return getArgument(FuelIndicatorLevelProperty);
}
};
// The message type of the FuelIndicator.UpdateLevel message.
static MessageType<FuelIndicatorUpdateLevelMessageArguments> FuelIndicatorUpdateLevelMessage;
FuelIndicator.UpdateLevel
message:// The message handler for the FuelIndicator.UpdateLevel message. // Shows the level of the Fuel Indicator in a Text Block 3D node. void fuelIndicatorUpdateLevelHandler(FuelIndicatorUpdateLevelMessageArguments& arguments) { // Get the level of the Fuel Indicator node. m_currentLevel += arguments.getFuelIndicatorLevel(); // Show the level of the Fuel Indicator node in a Text Block 3D node. TextBlock3DSharedPtr textBlock = m_textBlockReference.get(); if (textBlock) { textBlock->setText(to_string(m_currentLevel)); } }
initialize()
function register the message handler for the FuelIndicator.UpdateLevel
message:void initialize() { ... // Register the message handler for the FuelIndicator.UpdateLevel message. addMessageHandler(FuelIndicatorUpdateLevelMessage, this, &FuelIndicator::fuelIndicatorUpdateLevelHandler); }
FuelIndicator.UpdateLevel
message:MessageType<FuelIndicator::FuelIndicatorUpdateLevelMessageArguments> FuelIndicator::FuelIndicatorUpdateLevelMessage(kzMakeFixedString("Message.FuelIndicator.UpdateLevel"), KZ_DECLARE_EDITOR_METADATA ( // Set the name of the message the way you want to show it in Kanzi Studio. metadata.displayName = "Update Level"; // Show the message in the actions dropdown menu. metadata["Listenable"] = "False"; ));
To pass to Kanzi Studio information about the custom property types you create in a Kanzi Engine plugin, you declare metadata that describe these property types. The metadata enable Kanzi Engine plugin users to interact with the plugin content in Kanzi Studio. See Reference for showing Kanzi Engine plugin custom types in Kanzi Studio.
For example, to create the metadata for the custom property type VideoFileNameProperty to allow Kanzi Studio user to select a video file:
PropertyType<string> VideoView2D::VideoFileNameProperty(kzMakeFixedString("VideoView2D.VideoFileName"), "video.mp4", 0, false, KZ_DECLARE_EDITOR_METADATA ( // Set the name of the property type the way you want to show it in Kanzi Studio. metadata.displayName = "Video Filename"; // Set the tooltip for the property type. metadata.tooltip = "Name of the video file to be played"; // Set the category under which this property type is listed in the Properties. metadata.category = "Video"; // Set the editor you want the user to use to edit the value of this property type. // BrowseFileTextEditor editor contains a text box with a Browse button next to it. metadata.editor = "BrowseFileTextEditor"; // Set the default value of the property in Kanzi Studio. // The Kanzi Engine default value is set in the first line of this example. metadata["DefaultValue"] = "video.mp4"; ));
When the user adds a new VideoView2D node, Kanzi Studio
adds to the properties of the node in the category Video the Video Filename property, which has a text editor with a Browse button, a tooltip, and the default value set to video.mp4.
If you do not set the icon for your node type, Kanzi Studio uses the default icon (). To make it easier for Kanzi Studio users to visually keep track of the nodes in the Project, you can set your own icons for your nodes.
To set the icon for your node type:
For an example where a custom node type uses its own icon, see Node2D plugin example.
Reference for showing Kanzi Engine plugin custom types in Kanzi Studio